Pix refund received Webhook

info

📘 To learn more about webhooks in our API, follow the link below:

About Webhooks

In the event of a refund when a Pix is credited to your account, the best way to receive this information is using the webhook PIX_REFUNDED. As soon as a refund is received in your account, aPIX_REFUNDED weboohk is sent.

Here's the simplest way to configure a PIX_REFUNDED webhook:

Headers

Name	Description
x-delbank-api-key	Required. API key
x-delfinance-account-id	Required. The Delfinance bank account number

Body

{
  "eventType": "PIX_REFUNDED",
  "url": "https://example.com.br/webhooks/v1/pixrefundreceived", // Add your own URL here
  "authorization": "NONE,
  "authorizationScheme": "NONE"
}

Now once a Pix is refunded and credited to your account here's what you are going to receive on the registered URL:

PIX_REFUNDED

{
   "eventType": "PIX_REFUNDED",
   "endToEndId": "D38224857202502281818Xo3VqKXafNW",
   "originalEndToEndId": "E38224857202502281816OTCGIA6RVKG",
   "amount": 10,
   "bankAccount": "43028",
   "refundCode": "MD06",
   "reasonRefund": "Pedido reembolso",
   "idempotencyKey": "9ee5dfcb-8733-4271-bceb-64130171b616",
   "externalId": "13c5edd4-616e-43a1-aa80-c25b6ee15967",
   "createdAt": "2025-02-28T18:18:35.861Z",
   "proof": {
      "endToEndId": "D38224857202502281818Xo3VqKXafNW",
      "originalEndToEndId": "E38224857202502281816OTCGIA6RVKG",
      "status": "PIX_EFFECTIVE",
      "operationType": "CREDIT_REFUND",
      "amount": 10,
      "createdAt": "2025-02-28T18:18:35.776Z",
      "finishedAt": "2025-02-28T18:18:35.776Z",
      "description": "Pedido reembolso",
      "payer": {
         "number": "10138",
         "branch": "0001",
         "type": "CURRENT",
         "participant": {
            "name": "DELCRED SCD S.A.",
            "ispb": "38224857"
         },
         "holder": {
            "name": "FIDC DELCRED",
            "document": "11468192000181",
            "type": "LEGAL"
         }
      },
      "beneficiary": {
         "number": "43028",
         "branch": "0001",
         "type": "CURRENT",
         "participant": {
            "name": "DELCRED SCD S.A.",
            "ispb": "38224857"
         },
         "holder": {
            "name": "JOSE WILSON DOS SANTOS JUNIOR",
            "document": "498925*",
            "type": "NATURAL"
         }
      }
   }
}

Here are the attributes that are passed by the PIX_REFUNDED webhook:

Name	Description
eventType	The type of event that triggered the webhook (e.g., "PIX_REFUNDED").
endToEndId	The unique identifier for the refund PIX transaction.
originalEndToEndId	The unique identifier for the original PIX transaction that is being refunded.
amount	The monetary value of the refund PIX transaction.
bankAccount	The account number where the refund will be credited.
refundCode	A code representing the reason for the refund (e.g., "MD06").
reasonRefund	A textual description explaining the reason for the refund (e.g., "Devolução solicitada pelo cliente").
idempotencyKey	A unique key to ensure idempotency of the proof event processing.
externalId	External identification for reconciliation in the client system.
createdAt	The timestamp indicating when the refund PIX transaction was created.
proof	An object containing detailed proof information for the refund PIX transaction.
proof.endToEndId	The unique identifier for the refund PIX transaction within the proof context.
proof.originalEndToEndId	The unique identifier for the original PIX transaction within the proof context.
proof.status	The status of the refund PIX transaction (e.g., "PIX_EFFECTIVE").
proof.operationType	The type of operation being performed (e.g., "CREDIT_REFUND").
proof.amount	The monetary value of the refund PIX transaction within the proof context.
proof.createdAt	The timestamp when the refund process started.
proof.finishedAt	The timestamp when the refund process was completed.
proof.payer	An object containing information about the payer of the refund PIX transaction.
proof.payer.number	The account number of the payer.
proof.payer.branch	The branch number of the payer's account.
proof.payer.type	The type of the payer's account (e.g., "CURRENT").
proof.payer.participant	An object containing information about the financial institution of the payer.
proof.payer.participant.name	The name of the financial institution of the payer (e.g., "BANCO XXXXX").
proof.payer.participant.ispb	The ISPB code of the payer's financial institution.
proof.payer.holder	An object containing information about the holder of the payer's account.
proof.payer.holder.document	The document number of the payer (e.g., partially masked for security).
proof.payer.holder.type	The type of payer (e.g., "LEGAL" or "NATURAL").
proof.beneficiary	An object containing information about the beneficiary of the refund PIX transaction.
proof.beneficiary.number	The account number of the beneficiary.
proof.beneficiary.branch	The branch number of the beneficiary's account.
proof.beneficiary.type	The type of the beneficiary's account (e.g., "CURRENT").
proof.beneficiary.participant	An object containing information about the financial institution of the beneficiary.
proof.beneficiary.participant.name	The name of the beneficiary's financial institution (e.g., "DELCRED SCD S.A.").
proof.beneficiary.participant.ispb	The ISPB code of the beneficiary's financial institution (e.g., "38224857").
proof.beneficiary.holder	An object containing information about the holder of the beneficiary's account.
proof.beneficiary.holder.name	The name of the beneficiary (e.g., "EMPRESA LTDA").
proof.beneficiary.holder.document	The document number of the beneficiary
proof.beneficiary.holder.type	The type of beneficiary (e.g., "LEGAL" or "NATURAL").